/**
  * @(#)DatabaseClient.java
  *
  * Represent the application's interface to the database. The database
  * client is thread specific, as a result the transactions sets are
  * defined to also be thread specific. The transaction commits and 
  * rollbacks use thread-based storage for separating the changes from
  * one thread to another.
  *
  * @author Course Scheduler Team
  * 
  * @license GNU General Public License version 3 (GPLv3)
  *
  * This file is part of Course Scheduler, an open source, cross platform
  * course scheduling tool, configurable for most universities.
  *
  * Copyright (C) 2010-2012 Course Scheduler Team
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation, either version 3 of the License, or
  * (at your option) any later version.
  *
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  * 
  */
package com.pollicitus.scheduler.database;

import java.util.Collection;


/**
 * Represent the application's interface to the database. The database
 * client is thread specific, as a result the transactions sets are
 * defined to also be thread specific. The transaction commits and 
 * rollbacks use thread-based storage for separating the changes from
 * one thread to another.
 * 
 * @author Course Scheduler Team
 *
 */
/**
 * @author Course Scheduler Team
 *
 */
public abstract class DatabaseClient {

	//protected instance variables
	protected String databaseName;
	protected String databaseContext;
	
	/**
	 * Provide a standard method for committing changes back to the database.
	 * This implementation of this method determines the exact manner in
	 * which the commit is achieved, however the semantics must remain the
	 * same: all open modifications (context specific) since the last commit
	 * or rollback will be committed to the database.
	 */
	public abstract void commit();
	
	/**
	 * Provide a standard method for canceling changes to the database.
	 * This implementation of this method determines the exact manner in
	 * which the rollback is achieved, however the semantics must remain the
	 * same: all open modifications (context specific) since the last commit
	 * or rollback will be reverted in the database.
	 */
	public abstract void rollback();
	
	/**
	 * Close the connection from this database client to the database server.
	 * This method also removes this database client from the DatabaseManager
	 * memoization using the DatabaseManager.closeCleint(this) method. The
	 * DatabaseManager.closeClient(DatabaseClient) method also calls the
	 * database client's internalClose method to perform the actual client
	 * closing functionality.
	 */
	public void close(){
		//Application.dbManager.closeClient(this);
	}
	
	/**
	 * Perform closing and cleanup operations on this database client. This 
	 * method is called by the DatabaseManager.closeClient(DatabaseClient)
	 * method (in turn called by the DatabaseClient.close method) after the
	 * client has been removed from the DatabaseManager memoization structure.
	 */
	protected abstract void internalClose();
	
	
	/**
	 * Store the specified object into the database, adhering to database
	 * consistency semantics as required by the commit and rollback methods.
	 * Database client implementations should implement type specific versions
	 * of this method as required by the application.
	 * 
	 * @param <T> the type parameter specifying the class of the object being stored
	 * @param object the object to store into the database
	 */
	public abstract <T> void store(T object);
	
	
	/**
	 * Query for the specified object type using the parameters specified below.
	 * This method should function as a proxy for the actual query methods needed
	 * to query the object type.
	 * 
	 * @param <T>
	 * @param parms
	 * @return
	 */
	public abstract <T> Collection<T> query(Object... parms);
	
	
	/**
	 * Delete the specified object from the database, adhering to the database
	 * consistency semantics as required by the commit and rollback methods.
	 * Database client implementations should implement type specific versions
	 * of this method as required by the application.
	 * 
	 * @param <T> the typoe parameters specifying the class of the object being removed
	 * @param object the object to remove from the database
	 */
	public abstract <T> void delete(T object);
	

	/**
	 * Retrieve the database name for which this database client is valid.
	 * The Database Client is only connected to this database.
	 * 
	 * @return the databaseName for this database client
	 */
	public String getDatabaseName() {
		return databaseName;
	}

	/**
	 * Retrieve the database context for which this database client is valid. The
	 * Database Client should only be used within this context
	 * 
	 * @return the databaseContext for this database client
	 */
	public String getDatabaseContext() {
		return databaseContext;
	}

	/**
	 * Set the database name corresponding to this database client.
	 * 
	 * @param databaseName the databaseName to set
	 */
	protected void setDatabaseName(String databaseName) {
		this.databaseName = databaseName;
	}

	/**
	 * Set the database context corresponding to this database client
	 * 
	 * @param databaseContext the databaseContext to set
	 */
	protected void setDatabaseContext(String databaseContext) {
		this.databaseContext = databaseContext;
	}
}
